fts_open()¶

fts_open() 関数は、文字列ポインタの配列へのポインタを引き数に取る。 この文字列ポインタは、論理ファイル階層をつくる 1 つ以上のパスの名前になる。 配列は、 NULL ポインタで終端されなければならない。

多くのオプションがあり、少なくとも 1 つ (FTS_LOGICAL または FTS_PHYSICAL) が指定されなければならない。 次のオプションが or をとって選択される。

FTS_COMFOLLOW

このオプションは、 FTS_LOGICAL の指定にかかわらず、 ルートパスに指定されたシンボリックリンクをすぐにたどらせる。

FTS_LOGICAL

このオプションは、 fts ルーチンにシンボリックリンクそのものではなく、 シンボリックリンクが指しているファイルの FTSENT 構造体を返させる。 このオプションが設定された場合、 FTSENT 構造体がアプリケーションに返されるような シンボリックリンクのみが、存在しないファイルを参照している。 FTS_LOGICAL または FTS_PHYSICAL のどちらかを、 fts_open() 関数に与えなければ「ならない」。

FTS_NOCHDIR

パフォーマンスの最適化のため、 fts 関数群はファイル階層をたどるときディレクトリを変える。 これには、階層をたどっている間は アプリケーションがある特定のディレクトリにいるということに 依存できない、という副作用がある。 FTS_NOCHDIR オプションで最適化を無効にすると、 fts 関数群は現在のディレクトリを変更しない。 FTS_NOCHDIR が指定され、かつ fts_open() の引き数として絶対パス名が与えられたとき以外、アプリケーションは、 自らカレントディレクトリを変更したり、 ファイルにアクセスしたりすべきではない、という点に注意すること。

FTS_NOSTAT

デフォルトでは、返された FTSENT 構造体は、たどられた各ファイルについてのファイル特徴情報 ( statp フィールド) を参照する。 このオプションは、 fts 関数群が fts_info フィールドを FTS_NSOK に設定し statp の内容を定義されないままにすることを許すことにより、 パフォーマンスの最適化に必要なものを緩和する。

FTS_PHYSICAL

このオプションは、 fts ルーチンにシンボリックリンクが指しているファイルではなく、 シンボリックリンク自身の FTSENT 構造体を返させる。 このオプションが設定されると、階層中のすべてのシンボリックリンクの FTSENT 構造体がアプリケーションに返される。 FTS_LOGICAL または FTS_PHYSICAL のどちらかを fts_open() 関数に与えなければ「ならない」。

FTS_SEEDOT

デフォルトでは、 fts_open() のパス引き数として指定されない限り、ファイル階層中にある "." または ".." という名前のファイルは無視される。 このオプションは、 fts ルーチンにこれらのファイルの FTSENT 構造体を返させる。

FTS_XDEV

このオプションは、 fts が下り始めのファイルとは異なるデバイス番号を持っている ディレクトリに下りるのを阻止する。

引き数 compar() は、階層をたどる順番を決めるのに使われるユーザー定義関数を指定する。 この関数は、引き数として FTSENT 構造体のポインタのポインタを 2 つとり、 1 番目の引き数で参照されているファイルが 2 番目の引き数で参照されているファイルより 前にある場合は負の値・同じ場合はゼロ・後にある場合は正の値を 返さなければならない。 FTSENT 構造体の fts_accpath, fts_path, fts_pathlen フィールドは、この比較に「絶対」使ってはいけない。 fts_info フィールドが FTS_NS または FTS_NSOK に設定される場合、 fts_statp フィールドはこれらのどちらでもない。 compar() 引き数が NULL の場合、ディレクトリをたどる順番は、ルートパスについては path_argv のなかでリストされた順番で、 その他のファイルについてはディレクトリ内でリストされた順番となる。

fts_read()¶

fts_read() 関数は、階層中のファイルを記述する FTSENT 構造体へのポインタを返す。 (読み込み可能で、循環していない) ディレクトリは、 1 回は pre-order で、もう 1 回は post-order で、少なくとも 2 回たどられる。 他のファイルは、少なくとも 1 回たどられる。 (ディレクトリ間のハードリンクによって 循環やシンボリックリンクへのシンボリックリンクが起こらない場合、 ファイルは 2 回以上、ディレクトリは 3 回以上たどられる。)

階層中のすべてのメンバーが返された場合、 fts_read() は NULL を返し、外部変数 errno を 0 にする。 階層中のファイルに関係しないエラーが起こった場合、 fts_read() は NULL を返し、 errno をエラーに対応した値にする。 階層中のファイルに関係したエラーが起こった場合、 FTSENT 構造体へのポインタが返され、 errno は設定される場合と設定されない場合がある (fts_info を参照すること)。

fts_read() によって返される FTSENT 構造体は、同じファイル階層ストリームへの fts_close() の呼出しの後に上書きされる。 また、同じファイル階層ストリームへの fts_read() の呼出しの後でも、構造体がディレクトリを表現していない限り上書きされる。 この場合、 fts_read() 関数によって post-order で FTSENT 構造体が返された後、 fts_read() の呼出しがあるまで、 これらの構造体は上書きされない。

fts_children()¶

fts_children() 関数は、 FTSENT 構造体へのポインタを返す。 この構造体は、( fts_read() で最も新しく返された FTSENT 構造体で表現されるディレクトリにあるファイルの) NUL 終端されたリンクリストの最初のエントリを記述する。 このリストは、 FTSENT 構造体の fts_link フィールドを使ってリンクされ、 ユーザー指定の比較関数がある場合は、それで順序づけられる。 fts_children() の呼出しを繰り返すことで、 このリンクリストは再生成される。

特別な場合として、 fts_read() がファイル階層について呼ばれていない場合、 fts_children() は fts_open() に指定された論理ディレクトリ (つまり、 fts_open() に指定された引き数) の中にあるファイルへのポインタを返す。 それ以外の場合で、 fts_read() によって最も新しく返された FTSENT 構造体が pre-order でたどられたディレクトリでない場合や 何も含んでいないディレクトリの場合は、 fts_children() は NULL を返し、 errno を 0 にする。 エラーが起こった場合、 fts_children() は NULL を返し、 errno をエラーに対応した値にする。

fts_children() によって返される FTSENT 構造体は、同じファイル階層ストリームへの fts_children(), fts_close(), fts_read() の呼出しの後に上書きされる場合がある。

option は、次の値に設定できる。

FTS_NAMEONLY

ファイル名のみが必要とされている。 返された構造体のリンクリストの fts_name, fts_namelen フィールド以外の すべてのフィールドの内容は定義されない。

fts_set()¶

関数 fts_set() は、ユーザーアプリケーションが ストリーム ftsp のファイル f について更なる処理を決定すること許す。 fts_set() 関数は、成功した場合は 0 を、エラーが起こった場合は -1 を返す。 option は、次の値のいずれか 1 つに設定されなければならない。

FTS_AGAIN

ファイルを再びたどる。すべてのファイルタイプが再びたどられる。 次の fts_read() の呼出しにより、参照されているファイルが返される。 構造体の fts_stat, fts_info フィールドはこの時に初期化されるが、他のフィールドは変更されない。 このオプションは、 fts_read() によって最も新しく返されたファイルについてのみ意味を持つ。 通常は、post-order でディレクトリをたどる場合に使用し、 その下の階層と同様に、 ディレクトリを (pre-order と post-order の両方で) 再びたどらせる。

FTS_FOLLOW

参照されてるファイルは、シンボリックリンクでなければならない。 参照されているファイルが fts_read() によって最も新しく返されたものである場合、次の fts_read() の呼出しでは、シンボリックリンクそのものではなく、 シンボリックリンクが指している先を反映するように fts_info, fts_statp を再び初期化したファイルが返される。 ファイルが fts_children() によって最も新しく返されたものの 1 つである場合、 fts_read() によって返されたとき、構造体の fts_info, fts_statp フィールドは、シンボリックリンクそのものではなく、 シンボリックリンクが指している先を反映する。 どちらの場合でも、シンボリックリンクが指している先がないときは、 返された構造体のフィールドは変更されず、 fts_info フィールドが FTS_SLNONE に設定される。

リンク先がディレクトリの場合、 ファイルが pre-order で返された後、下の階層のすべてファイルが返され、 その後で post-order で返される。

FTS_SKIP

このファイルの下の階層はたどられない。 このファイルは、 fts_children() または fts_read() のどちらかによって最も新しく返されたものの 1 つである。

fts_close()¶

fts_close() 関数は、ファイル階層ストリーム ftsp を閉じる。そして、現在のディレクトリを ftsp を開くために fts_open() が呼ばれたディレクトリに復元する。 fts_close() 関数は、成功した場合は 0 を、エラーが起こった場合は -1 を返す。

エラー¶

関数 fts_open() が失敗した場合、 errno は、ライブラリ関数 open(2) と malloc(3) に対して指定されるエラーに設定される。

関数 fts_close() が失敗した場合、 errno は、ライブラリ関数 chdir(2) と close(2) に対して指定されるエラーに設定される。

関数 fts_read() と fts_children() が失敗した場合、 errno は、ライブラリ関数 chdir(2), malloc(3), opendir(3), readdir(3), stat(2) に対して指定されるエラーに設定される。

更に、 fts_children(), fts_open(), fts_set() が失敗した場合、 errno が次の値にされる。

EINVAL

オプションが無効であった。